Published on

Java Basic Series 1 - Understanding Java Classpath and Classloader

Authors

Understanding Java Classpath and Classloader

The Java Classpath is a parameter in the Java Virtual Machine or the Java compiler that specifies the location of user-defined classes and packages. The parameter may be set either on the command-line, or through an environment variable.

The Java ClassLoader is used to load .class files into the JVM at runtime. It lazily loads the bytecode of a class only when the class is first used.

Hence the classpath tells the classloader where to look in the filesystem for files defining these classes.

Setting the path to execute Java programs

Supplying as application argument

Suppose we have a package called de.marvbuss containing the classes:

  • DemoApplication (main class)
  • FirstClass
  • SecondClass

and the files defining this package are stored physically under the directory C:\myapplication (on Windows) or /home/user/myapplication (on Linux).

When we invoke Java, we specify the name of the application to run: de.marvbuss.DemoApplication. However we must also tell Java where to look for the files and directories defining our package. So to launch the program, we use the following command:

For Microsoft:

java -classpath C:\myapplication de.marvbuss.DemoApplication

For Linux

java -cp /home/user/myapplication de.marvbuss.DemoApplication

where:

  • java is the Java runtime launcher, a type of SDK Tool (A command-line tool, such as javac, javadoc, or apt)
  • -classpath C:\myapplication sets the path to the packages used in the program (on Linux, -cp /home/user/myapplication) and
  • de.marvbuss.DemoApplication is the name of the main class

Setting the path through an environment variable

The environment variable named CLASSPATH may be alternatively used to set the classpath. For the above example, we could also use on Windows:

    C:\myapplication>set CLASSPATH=C:\myapplication
    C:\myapplication>java de.marvnbuss.DemoApplication

The rule is that -classpath option, when used to start the java application, overrides the CLASSPATH environment variable. If none are specified, the current working directory is used as classpath. This means that when our working directory is C:\myapplication\ (on Linux, /home/user/myapplication/), we would not need to specify the classpath explicitly. When overriding however, it is advised to include the current folder . into the classpath in the case when loading classes from current folder is desired.

The same applies not only to java launcher but also to javac, the java compiler.

Setting the path of a Jar file

If a program uses a supporting library enclosed in a Jar file) called supportLib.jar, physically located in the directory C:\myapplication\lib\ the following command-line option is needed:

java -classpath C:\myapplication;C:\myapplication\lib\supportLib.jar de.marvbuss.DemoApplication

or likewise alternatively via the environment variable option.

Adding all JAR files in a directory

In Java 6 and higher, one can add all jar-files in a specific directory to the classpath using wildcard notation.

Windows example:

C:\myprogram>java -classpath ".;c:\mylib\*" MyApp

Linux example:

java  -classpath  '.:/mylib/*'  MyApp

This works for both -classpath options and environment classpaths.

Setting the path in a manifest file

If a program has been enclosed in a Jar filecalled demoApplication.jar, located directly in the directory C:\myapplication . The manifest file defined in demoApplication.jar has this definition:

Main-Class: de.marvbuss.DemoApplication Class-Path: lib/supportLib.jar

The manifest file should end with either a new line or carriage return.

The program is launched with the following command:

java -jar C:\myapplication\demoApplication.jar [app arguments]

This automatically starts de.marvbuss.DemoApplication specified in class Main-Class with the arguments. The user cannot replace this class name using the invocation java -jar. Class-Path describes the location of supportLib.jar relative to the location of the library demoApplication.jar. Neither absolute file path, which is permitted in -classpath parameter on the command line, nor jar-internal paths are supported. This means that if the main class file is contained in a jar, de/marvbuss/DemoApplication.class must be a valid path on the root within the jar.

Multiple classpath entries are separated with spaces:

Class-Path: lib/supportLib.jar lib/supportLib2.jar

Setting the path in IntelliJ IDE

Most IDEs have built-in support for setting the classpath. Let's check the steps for doing so in IntelliJ IDEA:

  • Left-click on File from the menu
  • Select Project Structure
  • Navigate to Modules
  • Click on Dependencies
  • Click on + at the bottom of the dialog
  • Add directories and JAR files and click on the Ok button

Main types of Classloaders

You can split class files based on their location and origin. For example you have:

  • Self-defined classes (written / located) in your application
  • System classes that come with the Java platform

Those types of classes correspond to different types of classloaders. The JVM searches for and loads classes in this order:

  1. bootstrap classes: the classes that are fundamental to the Java Platform (comprising the public classes of the Java Class Library, and the private classes that are necessary for this library to be functional). -> Bootsrap classloader
  2. extension classes: packages that are in the extension directory of the Java Runtime Environment or JDK, jre/lib/ext/ -> Extension Classloader
  3. user-defined packages and libraries -> System Classloader (loads classes from the classpath)*

*All classes that you write in your program and all the dependencies that from imported JARs are loaded by the System classloader